/**
 * ============邮件服务模块开始===========
 * 邮件服务 - Email Service
 * 
 * 功能说明：
 * - 提供邮件发送功能，主要用于发送验证码
 * - 支持SMTP协议发送邮件
 * - 集成nodemailer库，提供稳定的邮件发送服务
 * - 支持开发环境模拟发送（无需真实邮件配置）
 * 
 * 依赖模块：
 * - nodemailer: Node.js邮件发送库，支持多种邮件服务商
 * - logger: 日志记录工具，记录邮件发送状态和调试信息
 * 
 * 环境变量配置：
 * - MAIL_HOST: SMTP服务器地址（如：smtp.qq.com）
 * - MAIL_PORT: SMTP端口号（如：587）
 * - MAIL_SECURE: 是否使用SSL/TLS加密（true/false）
 * - MAIL_USER: 发送邮箱账号
 * - MAIL_PASS: 邮箱授权码或密码
 * 
 * 使用场景：
 * - 用户注册时发送验证码
 * - 用户找回密码时发送重置链接
 * - 重要操作通知邮件
 * 
 * Email service for sending verification codes and notifications
 */

// 导入依赖模块 - Import required modules
import nodemailer from "nodemailer";
import { logger } from "../utils/logger.js";

/**
 * ============邮件配置初始化开始===========
 * 从环境变量中获取邮件服务配置
 * Load email service configuration from environment variables
 * 
 * 配置说明：
 * - MAIL_HOST: SMTP服务器主机地址，不同邮件服务商有不同的SMTP服务器
 * - MAIL_PORT: SMTP端口，通常587用于STARTTLS，465用于SSL
 * - MAIL_SECURE: 是否启用SSL/TLS加密连接
 * - MAIL_USER: 发送方邮箱地址，需要开启SMTP服务
 * - MAIL_PASS: 邮箱授权码，不是登录密码，需要在邮箱设置中生成
 * 
 * 常见邮件服务商配置：
 * QQ邮箱: smtp.qq.com:587
 * 163邮箱: smtp.163.com:587
 * Gmail: smtp.gmail.com:587
 * Outlook: smtp-mail.outlook.com:587
 */
const { MAIL_HOST, MAIL_PORT, MAIL_SECURE, MAIL_USER, MAIL_PASS } = process.env;

/**
 * ============SMTP传输器创建开始===========
 * 创建nodemailer传输器实例
 * Create nodemailer transporter instance
 * 
 * 传输器配置说明：
 * - host: SMTP服务器地址
 * - port: SMTP端口号，转换为数字类型
 * - secure: 是否使用SSL/TLS，根据环境变量字符串转换为布尔值
 * - auth: 认证信息，包含用户名和密码/授权码
 * 
 * 安全性考虑：
 * - 使用授权码而非登录密码，提高安全性
 * - 支持SSL/TLS加密传输，保护邮件内容
 * - 敏感信息通过环境变量配置，避免硬编码
 */
const transporter = nodemailer.createTransporter({
  host: MAIL_HOST,                    // SMTP服务器地址 - SMTP server host
  port: Number(MAIL_PORT),            // SMTP端口号，转换为数字 - SMTP port number
  secure: MAIL_SECURE === "true",     // 是否使用SSL/TLS加密 - Whether to use SSL/TLS encryption
  auth: {
    user: MAIL_USER,                  // 发送方邮箱地址 - Sender email address
    pass: MAIL_PASS,                  // 邮箱授权码 - Email authorization code
  },
});

/**
 * ============发送邮件验证码功能开始===========
 * 发送邮件验证码
 * Send email verification code
 * 
 * @param {Object} params - 邮件发送参数对象
 * @param {string} params.email - 接收方邮箱地址，必须是有效的邮箱格式
 * @param {string} params.code - 验证码，通常是6位数字或字母数字组合
 * @returns {Promise<void>} 无返回值，发送成功会记录日志
 * @throws {Error} 当邮件发送失败时抛出异常
 * 
 * 功能说明：
 * - 支持开发环境模拟发送，无需配置真实邮件服务
 * - 生产环境使用真实SMTP服务发送邮件
 * - 自动记录发送状态和消息ID，便于追踪和调试
 * - 使用HTML格式邮件，提供更好的用户体验
 * 
 * 邮件内容设计：
 * - 发送方显示为"星命之境"品牌名称
 * - 主题明确标识为验证码邮件
 * - 内容使用尊敬的称呼，提升用户体验
 * - 验证码使用粗体显示，便于识别
 * - 明确标注有效期，避免用户困惑
 * 
 * 使用示例：
 * await sendEmailCode({
 *   email: 'user@example.com',
 *   code: '123456'
 * });
 * 
 * 异常处理：
 * - 网络连接失败：检查网络连接和SMTP服务器状态
 * - 认证失败：检查邮箱账号和授权码是否正确
 * - 邮箱地址无效：验证接收方邮箱地址格式
 * - 发送频率限制：某些邮件服务商有发送频率限制
 * 
 * 安全性考虑：
 * - 验证码应该有时效性，通常5-10分钟
 * - 验证码应该是随机生成，避免被猜测
 * - 发送频率应该有限制，防止恶意请求
 * - 敏感信息不应该记录在日志中
 */
export const sendEmailCode = async ({ email, code }) => {
  // 第一步：检查邮件服务配置 - Step 1: Check email service configuration
  // 如果没有配置邮件服务（开发环境），则模拟发送
  // 这样可以在没有真实邮件服务的情况下进行开发和测试
  if (!MAIL_USER || !MAIL_PASS) {
    logger.info("💌 模拟发送邮件验证码 - Simulating email verification code sending", { 
      email, 
      code,
      note: "开发环境模拟发送，生产环境请配置真实邮件服务"
    });
    return;
  }

  try {
    // 第二步：发送邮件 - Step 2: Send email
    // 使用nodemailer发送HTML格式的验证码邮件
    const info = await transporter.sendMail({
      from: `"星命之境" <${MAIL_USER}>`,           // 发送方，显示品牌名称 - Sender with brand name
      to: email,                                  // 接收方邮箱地址 - Recipient email address
      subject: "星命之境 - 验证码",                // 邮件主题 - Email subject
      html: `
        <div style="font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px;">
          <div style="text-align: center; margin-bottom: 30px;">
            <h1 style="color: #4A90E2; margin: 0;">星命之境</h1>
            <p style="color: #666; margin: 5px 0;">您的专属命理顾问</p>
          </div>
          
          <div style="background: #f8f9fa; padding: 30px; border-radius: 10px; text-align: center;">
            <h2 style="color: #333; margin-bottom: 20px;">邮箱验证码</h2>
            <p style="color: #666; font-size: 16px; margin-bottom: 20px;">
              尊敬的星命探索者，您正在进行邮箱验证
            </p>
            
            <div style="background: white; padding: 20px; border-radius: 8px; margin: 20px 0;">
              <p style="color: #333; font-size: 18px; margin-bottom: 10px;">您的验证码为：</p>
              <div style="font-size: 32px; font-weight: bold; color: #4A90E2; letter-spacing: 5px; margin: 15px 0;">
                ${code}
              </div>
            </div>
            
            <p style="color: #999; font-size: 14px; margin-top: 20px;">
              验证码有效期为 <strong>5 分钟</strong>，请及时使用
            </p>
            <p style="color: #999; font-size: 12px; margin-top: 15px;">
              如果您没有请求此验证码，请忽略此邮件
            </p>
          </div>
          
          <div style="text-align: center; margin-top: 30px; padding-top: 20px; border-top: 1px solid #eee;">
            <p style="color: #999; font-size: 12px;">
              此邮件由系统自动发送，请勿回复
            </p>
          </div>
        </div>
      `,                                         // HTML格式邮件内容 - HTML email content
    });
    
    // 第三步：记录发送成功日志 - Step 3: Log successful sending
    logger.info("邮件发送成功 - Email sent successfully", {
      messageId: info.messageId,                  // 邮件消息ID，用于追踪 - Message ID for tracking
      recipient: email,                           // 接收方邮箱（脱敏处理） - Recipient email (masked)
      timestamp: new Date().toISOString()         // 发送时间戳 - Sending timestamp
    });
    
  } catch (error) {
    // 第四步：错误处理 - Step 4: Error handling
    logger.error("邮件发送失败 - Email sending failed", {
      error: error.message,                       // 错误信息 - Error message
      recipient: email,                           // 接收方邮箱 - Recipient email
      timestamp: new Date().toISOString()         // 错误发生时间 - Error timestamp
    });
    
    // 重新抛出异常，让调用方处理
    throw new Error(`邮件发送失败: ${error.message}`);
  }
};
